#!/usr/bin/env python
"""
Addama Repository Services

Provides an API for repository services via addama-rest.

For more information, please see the documentation in README.txt, or simply
issue help() on any function or module contained within this package.

For license information, please see LICENSE.txt.


Author: Tom Robinson <trobinson@systemsbiology.org>
Initial Revision: April 14th, 2010

"""

# Imports

import cookielib
import urllib2


# Functions

def get(url, authCookies=None):
    """Gets the supplied repository node, testing it in the process
    Returns the URL to this repository on success; None otherwise"""
    
    # Preconditions
    if len(url) == 0:
        raise ValueError

    # Build a cookie jar object if one isn't provided    
    if not authCookies:
        authCookies=cookielib.CookieJar()

    opener = urllib2.build_opener(urllib2.HTTPCookieProcessor(authCookies))
    try:
        request = opener.open(url)
        return url
    except IOError:
        return None


# Output help text if this script is invoked directly
if __name__ == "__main__":
    print """
This script should not be run directly.

To include it in your project, simply import it from addama:
import <directory>
from <module> import <submodule>

For example:
import addama.api
from addama import api

(Note these two invocations differ as to the syntax of the final module)

"""

